feat(setup): the guide's consent lands on the change, not the look [spec 03-03] - #125

Implements specs/spec03/03-03-guide-harness.md (§3 flow amendment — consent lands on the change, not the look).

What

Field testing the stale-yt-dlp repair (PR #124) surfaced real friction: the user answers y on the checklist card ("walk me through fixing them"), and the guide then re-asks y/N for every tool call — including pure diagnostics like which -a yt-dlp; yt-dlp --version and brew info. The wall of confirms buries the one that matters (brew upgrade).

cliPermission now auto-allows what can only look:

• the read-only builtins Read / Glob / Grep (Write/Edit still ask);
• Bash commands whose every segment is provably read-only (isReadOnlyCommand): the command is split at every separator (;, &&, ||, |, &, newline) and around $(...), and each segment must match a conservative allowlist (which/ls/echo/version-reads/brew info-list/uv tool list/…). One unknown head poisons the whole command → falls back to asking.

Everything that can mutate — installs, upgrades, Write/Edit, anything unrecognized — keeps the per-action y/N. bypassPermissions remains forbidden (the red line and its guard test stand). Auto-allows are recorded in the dev log.

Hardened by review (each with a regression test):

• Credential boundary kept: parameter expansion disqualifies ($ passes only as $? or an allowlisted $(...)) so echo $MURMUR_TTS_API_KEY cannot slide a secret into the SDK transcript; secret-bearing targets (voice.json, .env*) never auto-allow for any tool — the §7.2 out-of-band secret flow stays intact.
• brew outdated excluded: default Homebrew auto-updates its own metadata before answering it — that mutates state, so it asks.

Verification

• pnpm test (785), pnpm run typecheck, oxlint — all green.
• The auto-allow test replays the exact compound commands from the user's field-test screenshot; classifier tests pin the refusals (redirects, backticks, $VAR, chained mutations, brew outdated, secret paths).
• Peer review (codex gpt-5.5, xhigh): 2 findings, 2 applied (credential-read consent, brew outdated auto-update).

AI coding brief

• Original request: after live-testing the setup guide, the user asked why murmur demands confirmation for every step instead of running more automatically.
• Manual interventions: the user chose the middle path from three offered options — auto-allow read-only investigation, keep per-action consent for mutations — rather than full auto-mode, which would have broken the project's bypassPermissions red line.
• Retro: the original per-action design shipped without a field pass on how many asks a typical repair generates; a dry-run transcript during spec review would have caught the friction before it reached the user.

🤖 Generated with Claude Code